Repository navigation
README: clarify tables.create vs tables.load - #96
jirkasemmler wants to merge 1 commit into
Conversation
The README only showed tables.create under a generic "save data" comment, while the developer docs show tables.load. Both are correct but do different things: create makes a new table from a CSV file, load imports data into an existing table (full or incremental). Show both so the two documents no longer look contradictory. Fixes #84 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
martinsifra
left a comment
There was a problem hiding this comment.
Review summary
This docs-only change fixes #84. It replaces the vague # save data comment in both README usage blocks with explicit tables.create (new table) and tables.load (existing table, full or incremental) examples.
- Every documented call matches the current signatures:
createatkbcstorage/tables.py:74,loadat:209. - The table id and file path in the load examples line up with the preceding
createandexport_to_filecalls. - The load semantics in the comments match the Storage docs (Incremental Loading).
- The branch is behind master (#94), but it merges cleanly, and the merged README reads fine next to the new
StorageApiTokenexamples.
No blockers. Two optional wording nits.
Nits
1. The two usage blocks describe is_incremental differently. The lines are README.md:61 and README.md:31-35.
- The client-class block says incremental means "append rows / upsert by primary key".
- The endpoint-class block says
is_incremental=Truemeans "append instead of replace". That is only true for tables without a primary key. - Same flag, two descriptions: the kind of README-vs-README mismatch #84 was about.
Suggested wording, the same in both blocks:
# load data into an existing table (full load truncates the table first)
# ... is_incremental=True appends rows, or upserts them if the table has a primary key2. The create example has no primary key, so the upsert case never applies (README.md:28-35).
some-table-2is created withoutprimary_key, so the incremental load right after it only appends.- Optionally show
primary_key=['id'], as the developer docs do. - Optionally also say that
createfails when the table already exists. That is the other half of create vs load. - The current text is not wrong.
Notes, not blocking
- The failing
Run tests (AWS/Azure/GCP)checks are pre-existing.- Master
fa5df8efails the sametests/functional/test_tables.pycases on all three stacks:buckets.create400 insetUp,Application errorjobs,bucket not foundintearDown. - A README-only diff cannot cause them. The build and mock tests pass.
- Master
- Pre-existing bug, out of scope for this PR:
Tables.load(columns=[...])has no effect.load_rawsends the list asprimaryKey[](kbcstorage/tables.py:292-293). The Storageimport-asyncendpoint reads it ascolumnsand ignores unknown parameters, so the column list is dropped silently, e.g. together withwithout_headers=True.- The README doesn't document
columns=, so this is unrelated to this change. It's worth a separate issue or PR.
martinsifra
left a comment
There was a problem hiding this comment.
This docs-only change fixes #84. It replaces the vague # save data comment with explicit tables.create (new table) and tables.load (existing table, full and incremental) examples.
- Every documented call matches the current signatures.
- The load semantics match the Storage docs.
- The branch merges cleanly with current master.
No blockers. The two optional wording nits are in the review above. The red CI is pre-existing on master and unrelated.
Why
#84 reports a conflict between the README (
tables.createunder a generic "save data" comment) and the developer docs (tables.load). Both are correct, they just do different things and the README did not say so.What
Replace the "save data" example with explicit examples for:
tables.create– create a new table from a CSV filetables.load– load data into an existing table, full or incrementalFixes #84
🤖 Generated with Claude Code